Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EODetailDatabaseDataSource

Inherits From:	NSObject

Conforms To:	EODataSources (through EOMasterDataSources)
EOMasterDataSources
EOQualifiableDataSources
EORollbackDataSources

Declared In:	eoaccess/EODetailDatabaseDataSource.h

Class Description

An EODetailDatabaseDataSource is a detail data source, as described in the EOQualifiableDataSources protocol specification; its master data source handles all fetching and modifications of the objects it supplies. You create an instance of this class by sending dataSourceQualifiedByKey: to an EODatabaseDataSource or another EODetailDatabaseDataSource and then specifying a master object with qualifyWithRelationshipKey:ofObject:. The master object must be able to provide other enterprise objects for the relationship key specified.

An EODetailDatabaseDataSource uses its master to perform its insert, delete, update, and fetch operations. Thus, changes made in the detail data source are reflected in the objects managed by the master data source.

Note that an EODetailDatabaseDataSource can itself have a detail data source. A series of EODetailDatabaseDataSources shares a single EODatabaseDataSource, which is returned by the masterDataSource method of each detail data source. Note that this differs from the usual sense of ªmaster data source,º which typically refers to the immediate master, not the root master.

Instance Variables

None declared in this class.

Adopted Protocols

EODataSources	- keys
- coerceValue:forKey:
- fetchObjects
- saveObjects
- createObject
- insertObject:
- canDelete
- deleteObject:
- updateObject:

EOMasterDataSources	- dataSourceQualifiedByKey:

EOQualifiableDataSources	- qualifyWithRelationshipKey:ofObject:

EORollbackDataSources	- rollback

Method Types

Initializing instances	- initWithMasterDataSource:entity:

Getting the master data source	- masterDataSource

Getting the entity	- entity

Getting the detail key	- detailKey

Getting the objects	- masterObject
- array

Instance Methods

array

- (NSArray *)array

Returns the array of objects supplied by the receiver. This array contains the destination objects corresponding to the relationship key in the master enterprise object. An EODetailDatabaseDataSource's array is established when it's qualified with qualifyWithRelationshipKey:ofObject:.

canDelete

@protocol EODataSources
- (BOOL)canDelete

Returns NO if the data source's entity is read-only or if its relationship is to-one, YES otherwise.

See also:  - isReadOnly (EOEntity)

coerceValue:forKey:

@protocol EODataSources
- coerceValue:aValue forKey:(NSString *)key

Returns aValue as an instance of the value class defined for the attribute named key of the receiver's entity. Returns nil if aValue couldn't be coerced to the new type.

For example, suppose the Employee entity has an attribute named dateHired with a value class of NSCalendarDate. If you send coerceValue:forKey: to a database data source with an NSString as the value and ªdateHiredº as the key, it creates an NSCalendarDate from the string value and returns it.

See also:  - entity, - valueClassName (EOAttribute)

createObject

@protocol EODataSources
- createObject

Returns a new enterprise object with no values set, allocated from the data source's zone and initialized as described below, or nil if the receiver's EOEntity is read-only. The sender of this message is responsible for setting the enterprise object's property values (especially its primary key) and for then inserting the newly created object into the data source.

If the new enterprise object responds to initWithPrimaryKey:entity: it's initialized with that method, with nil as the primary key and with the data source's entity. If the enterprise object doesn't respond to initWithPrimaryKey:entity:, it's initialized with init.

dataSourceQualifiedByKey:

@protocol EOMasterDataSources
- (id <EOQualifiableDataSources>)dataSourceQualifiedByKey:(NSString *)relName

Returns a new EODetailDatabaseDataSource that provides objects for the destination of the relationship named relName of the receiver's entity. Before using the returned detail data source you have to assign it a master object with qualifyWithRelationshipKey:ofObject:.

Returns nil if the receiver can't supply a detail data source for relName (typically because its entity has no relationship of that name).

See also:  - entity

deleteObject:

@protocol EODataSources
- (BOOL)deleteObject:anEO

Sends deleteObject: to the receiver's master data source with anEO as the argument. Returns YES on success and NO on failure, if the receiver's entity is read-only, if its relationship is to-one and the property in the master does not represent a valid object, or if it has no objects. For to-one relationships, deleteObject: sets the property in the master to EONull.

See also:  - isReadOnly (EOEntity), - canDelete

detailKey

- (NSString *)detailKey

Returns the name of the relationship in the master object's entity. The EODetailDatabaseDataSource provides the destination objects for this relationship. The detail key is established when the receiver is sent a qualifyWithRelationshipKey:ofObject: message.

The objects supplied by the master data source must have a class property matching the detail key, which the detail data source uses to get the destination objects for its relationship.

See also:  - masterObject

entity

- (EOEntity *)entity

Returns the entity that the receiver supplies object for. An EODetailDatabaseDataSource's entity is established as the destination entity of the relationship specified in a qualifyWithRelationshipKey:ofObject: message.

fetchObjects

@protocol EODataSources
- (NSArray *)fetchObjects

Returns the array of objects supplied by the receiver, or nil if an error occured. This array contains the destination objects corresponding to the relationship key in the master enterprise object. EODetailDatabaseDataSources don't actually fetch, but get their objects from their master object by using the key-value coding method valuesForKeys: with the detail key.

See also:  - array, - masterObject, - detailKey

initWithMasterDataSource:entity:

- initWithMasterDataSource:(EODatabaseDataSource *)masterDataSource
entity:(EOEntity *)anEntity

Initializes a newly allocated EODetailDatabaseDataSource with the given information. This is the designated initializer for the EODetailDatabaseDataSource class. Returns self.

Instances of this class are normally created by sending dataSourceQualifiedByKey: to an EODatabaseDataSource or an existing EODetailDatabaseDataSource. You should never allocate and initialize an EODetailDatabaseDataSource directly.

insertObject:

@protocol EODataSources
- (BOOL)insertObject:anEO

Sends insertObject: to the receiver's master data source with anEO as the argument. Returns YES on success, NO on failure, if the receiver's entity is read-only, if its relationship is to-one and the property in the master is neither nil nor EONull, or if it has no objects.

See also:  - isReadOnly (EOEntity)

masterDataSource

- (EODatabaseDataSource *)masterDataSource

Returns the EODatabaseDataSource at the root of a series of EODetailDatabaseDataSources. Note that the meaning of ªmasterº in this method name differs from that in masterObject, which returns an object in the immediate master data source.

masterObject

- masterObject

Returns the source object for the receiver's relationship. The objects provided by the receiver are the destination objects of this object's relationship. The master object is established by the qualifyWithRelationshipKey:ofObject: method.

See also:  - detailKey, - fetchObjects

qualifyWithRelationshipKey:ofObject:

@protocol EOQualifiableDataSources
- (void)qualifyWithRelationshipKey:(NSString *)relName
ofObject:anEO

Qualifies the receiver so that it supplies objects based on relName, which is the name of a relationship of anEO (that is, a key of the form used with the EOKeyValueCoding protocol messages). anEO becomes the master object of the receiver and relName becomes its detail key.

If anEO is nil, this method causes the data source to return no objects when sent a fetchObjects or array message.

See also:  - masterObject

rollback

@protocol EORollbackDataSources
- (void)rollback

Sends rollback to the receiver's master data source. Returns YES on success, NO on failure.

saveObjects

@protocol EODataSources
- (BOOL)saveObjects

If the receiver has any objects to save, updates its master object with the new array of objects for its relationship and sends saveObjects to the receiver's master data source. Returns YES on success, NO on failure.

See also:  - array

updateObject:

@protocol EODataSources
- (BOOL)updateObject:anEO

Sends updateObject: to the receiver's master data source with anEO as the argument. Returns YES on success, NO on failure, if the receiver's entity is read-only, or if the receiver has no objects.

See also:  - isReadOnly (EOEntity), - array